Scene authoring tools

The Scene authoring tools are used for the creation and editing of molecular scenes. Scenes created using the Scene authoring tool can then be inserted into Proteopedia pages.

Where are the Scene authoring tools
A good place to start is the Video on Adding Scenes.

The Scene authoring tools are accessible when you are editing a page. Click the tab edit this page at the top of the page where you wish to create a molecular scene. On the edit page, near the top, you'll see a big box where all the wikitext of the page lives--here you can change the text of the page. If you scroll down some, near the bottom, you'll find in bold letters Scene authoring tools [show]. Click on show to expand and open the Scene authoring tools.

Overview
A good place to start is the Video on Adding Scenes.

Next you may want to look at the Instructions for creating a molecular scene with Proteopedia's Scene Authoring Tools.

The Scene authoring tools are meant to make scene management easier and to make scene creation easier. Scenes are "frozen" moments in Jmol that can be later restored. A scene stores viewpoint, representations, colors, labels, and generally everything that is necessary to recreate the way things looked when the scene was saved.

The steps of using the Scene authoring tools are as follows:
 * 1) Either load an existing scene using the 'load scene' tab, or start fresh with the 'load molecule' tab.
 * 2) Manipulate the scene view using the mouse. Change the scene appearance by choosing selections from your scene using the 'selections' tab and setting the appearance of selections using the 'representations', 'colors' and 'labels' tabs.
 * 3) Save the scene using the 'save scene' tab, and wikitext for inserting the scene into a Proteopedia page will be automatically generated.

So the idea is to begin by either loading an existing scene, or by loading a molecule. Once something is loaded onto the Jmol applet, you can begin to change the viewpoint, the representations, the colors, the labels, and other settings, in order to create a scene that conveys your desired message. When you're done creating the scene, you save it and then put it into the page.

'load scene' tab
The first input box asks for the page name (on which the scene you wish to load resides). The default page name is the name of the page currently being entered. Next, you proceed to choose the scene name using the drop-down selector (all scenes associated with the entered page name will be listed). Once a scene is selected, all of its versions are available for selection using the drop-down version number menu. When a version number is selected, that version of the scene is loaded onto the Jmol applet that is part of the Scene authoring tools and the description that was given to the scene is also recalled. At the same time, the wikitext that is needed for insertion of the scene into the page is displayed.

Each distinct scene has 3 parameters to distinguish it from all other scenes: pagename, scenename, and versionnumber. A scene's "pagename" is automatically determined by the name of the Proteopedia page on which the scene was initially created. The scenename is given by the user. The versionnumber is incremental: If no scene by the given name exists for the given page, then the first version will be version 1. If there exist previous versions of the same scenename on the same pagename, then the newest saved version will not overwrite older versions of the scene, but will instead be automatically saved as the newest version (by incrementing the versionnumber by one). A scene's full name is in this format: Pagename/Scenename/Versionnumber (ex: Hemoglobin/Cavity/14).

'load molecule' tab
The load molecule tab is used to load molecules into Jmol. Currently only one file can be loaded into Jmol at a time through this interface (but Jmol can handle several files at a time).

To load a file that has PDB code, input a PDB code into the first input area and click the load button. The file will be fetched from the PDB database throgh OCA.

To load a file that is not part of the PDB, first upload the file to Proteopedia at Special:Upload (you can get there also by using the link called 'upload file' on the left hand column-toolbar of Proteopedia). Once a file has been uploaded, you can specify its name in the input area next to the words "From Proteopedia upladed file" and click load.

The "currently loaded" text area displays the name of the currently loaded file in the Jmol applet of the "Scene authoring tools".

'selections' tab
The selections tab is meant to be used to select particular groups of atoms so that you can later change that group's color, representations, or labels. When you choose a representation, a color, or a label using the Scene authoring tools other tabs, the change is almost always applied ONLY to the currently selected atoms. That is why it is important to be aware of what atoms are selected at any given time.

selection halos
To see which atoms are selected, turn 'selection halos' on using the selection halos checkbox. If you have something selected, you will see your selection highlighted by yellow halos. These halos are NOT part of your scene and have no impact other than to indicate to you what atoms are currently selected.

all or nothing and halos
This box contains two buttons and a checkbox. 'Select all' selects all atoms. 'Select none' selects none. 'Selection halos' toggles whether selection halos are shown to highlight the current selection.

add to or remove from selection
This is the main tool for creating selections. This box allows you to specify groups of atoms to either ADD to the current selection, or REMOVE from the current selection. It is advised to either begin with ALL atoms selected and then use this box to REMOVE atoms to your selection to arrive at your desired selection, or alternatively to begin with NO atoms selected and then use this box to ADD atoms to your selection to arrive at your desired selection.

It is advised that you use selection halos while creating a selection so that you may view the atoms that your selection comprises.

Each input box allows you to specify certain parameters in order to best choose what to add or remove to/from your selection. There is an imaginary 'AND' (or intersection) connecting each input box (a Boolean AND), but an 'OR' (or union) connecting the chosen elements within each input box. What this means is that if you choose in the 'groups' box the items 'all protein' and 'dna' and in the 'limit to elements' box you type in 'C,O' and click "add to selection", then you will add to your selection all the carbon and oxygen atoms that are part of either the protein or the dna in your loaded file (it's like saying "(all protein OR dna) AND (carbon OR oxygen)" )

The 'groups' box lists various pre-defined groups of atoms by name. The 'limit to chains' box allows you to choose specific chains by the names they are given in the loaded file (ex: A,C,D). The 'limit to resi types' allows specification of residues by their 3-letter codes (ex: PHE,ALA,GLY). The 'limit to residue nos' box allows specification of residues by their number (ex: 18,23-25,32). The 'limit to elements' box allows choosing specific elements or even specific isotopes (ex: Fe,2H,31P). The 'limit to atom nos' box allows specifying atoms by their number. The 'sites' box appears only if your file is a PDB file that has predefined sites that the authors defined when they submitted the file to the Protein Data Bank.

The button 'add to selection' checks the information that was specified by you in the boxes in the 'add to or remove from selection' area and then adds what you specified into the current selection. The 'remove from selection' does the same, but rather than adding to the current selection, it removes from the current selection.

select within distance
Here you may enter a value (in Angstroms) and press 'go'. Any atom within a distance from the current selection equal to or smaller than the the number of Angstroms you specifed will be added to the selection. To clarify, an example: If you had a ligand selected, and then inputted 5 and hit 'go', then all atoms within 5 Angstroms of that ligand would be added to your selection. Your selection would then be composed of the ligand as well as all atoms within 5 Angstroms of it.

mouse click selects
Choosing 'default' sets it so that mouse clicks on the Jmol applet are set to their default setting in Jmol. In the default setting, clicking does not select or deselect any atoms, but clicking to create measurements is enabled. Choosing 'center' makes it so that any click on an atom, centers both the view and the axis of rotation on the atom. Choosing 'atom' is perhaps the most useful setting for creating selections as each click on an atom either adds it to the selection, or if it is already part of the selection, removes it from the selection. Choosing 'element' makes it so that clicking on an atom will select all other atoms of the same element. Choosing 'molecule' makes it so that clicking on an atom selects all other atoms of the same molecule.

'representations' tab
The first area is the 'all and halo toggle' area. This provides a button to select all atoms, and a checkbox to turn selection halos on or off.

The 'set selection representation' box provides a variety of choices for setting the representation of the current selection. Multiple representations can be turned on for the same selection of atoms (for instance using both wireframe and spacefill can create a 'ball and stick' scheme). Click on the representations that you would like to turn on for your current selection and then press 'set representation'. Every representation that has been checked off (to the left of the representation's name) will be displayed. Some representations have an input field to their direct right. If they do, then you may enter values in order to change the form of the representation, usually its size. If you leave the input field blank, the default will be used.

Clicking on 'hide selection' turns off all representations for the selection.

'colors' tab
The first area is the 'all and halo toggle' area. This provides a button to select all atoms, and a checkbox to turn selection halos on or off.

The 'color' area first lets you choose whether you would like to change the color of the current selection, or of the background. The color palette is clickable and as soon as you click on a color, either your selection or the background (as was previously selected) will change to the clicked color. Hover over a color to view its name. There is a series of buttons below the color palette, each representing a specific color scheme.

CPK is the standard CPK coloring scheme. Amino and amino2 color each amino acid as a different color. Chain colors each chain different colors. Spectrum colors protein and nucleic acids from blue to red on a spectrum with the N or 5' terminus as blue and the C or 3' terminus as red. Structure colors according to secondary structure. Fixed and relative temperature color according to temperature and formal and partial charge according to charge. DRuMS composition colors according to the DRuMS scheme (http://www.umass.edu/molvis/drums/). Hydrophobic/polar colors hydrophobic amino acids grey and polar (charged or uncharged) residues pink. Charge colors hydrophobic residues grey, polar-uncharged residues pink, cationic residues blue, anionic residues red, and backbone atoms purple whether charged or uncharged. More information on Jmol colors is available at http://jmol.sourceforge.net/jscolors/.

The 'transparency' area allows you to render your selection transparent. Zero percent transparent will be opaque, 100 percent transparent will be invisible, and anywhere in between will be transparent to a degree.

'labels' tab
The first area is the 'all or nothing and halo toggle' area. This provides a button to select all atoms, disselect all atoms (select none), and a checkbox to turn selection halos on or off.

The 'mouse click selects' area is similar to the 'mouse click selects' area in the 'selections' tab and allows changing between the 'default' mouse picking style and the 'atom' mouse picking style. See the 'selections' tab section above for an explanation about the different mouse picking styles.

The 'label atoms' area is used to label atoms. First, an atom must be selected. Next, you choose how the label should look by choosing between entering text, displaying the atom name, the element, the 3-letter residue code, the residue number, and the chain letter of the atom being labeled (you can combine all of these options however you want). When you are ready to create the label, click on 'set label'. Note that if you have a selection of atoms when you assign a label by clicking 'set label', then each atom in the selection will get a label. 'Clear labels from selection' will clear all the labels from the current selection. To delete all labels, first 'select all' and then 'clear labels from selection'.

To change the label properties, you can choose label color, label size, and an optional pointer from the label to the atom.

The following three areas are collapsed by default and may be expanded and collapsed by clicking the +/- near their names:

The 'label applet' tab allows setting of a label that will be displayed in the bottom area of the applet. Its color and size can be chosen. Use 'set label' to set the label after entering text. Use 'clear label from applet' to clear the label. To have an applet label that takes up multiple lines, use the symbol | to create line breaks in your inputted text. Label color and size can be changed after or before setting a label.

The 'measurements' area allows control over the appearance of measurements. Measurements can be created by a combination of double and single clicking on atoms while in the 'default' mouse picking setting. Measurements are explained in the 'how to' tab of the Scene authoring tools. Here in the 'measurements' area, you can control the color, size, and units of the measurements. Changing the color or the size will affect all existing and future measurements but changing the units will only affect future measurements. The labels on the measurements can also be turned off or on.

The 'bonds' area allows control over disulfide and hydrogen bonds. You can turn disulfide and/or hydrogen bonds on or off for a particular selection and can choose the colors for the bonds.

'save scene' tab
Once you have created your scene, you can save it here.

You must choose a name for your scene, and enter a description. If you started by loading a scene, then by default, its name will appear as a suggested name for the scene you are about to save because Proteopedia assumes you might be editing a scene to save an updated version. If you specify the name of a scene that already exists, then your scene will be saved as the newest version (i.e. if versions 1 through 5 for that scene already exist, then your scene will be saved as version 6).

After saving, wikitext for inserting your scene into the Proteopedia page will appear in the 'Wikitext' area.

'advanced options' : choosing a non-standard scene transition
If you select the checkbox entitled 'advanced options', you get two choices for non-standard transitions. This means you can choose different transitions for how your scene will be recalled when the user clicks on the green scene link. Here's the breakdown of transition options:


 * 1) If you don't select any checkbox (i.e. do not select the checkbox next to "show advanced options") then the most basic and standard transition will be used : when the scene is recalled, the molecule will zoom out to 100% zoom, rotate to the new scene's orientation, and then zoom to the new scene's correct zoom.
 * 2) If you select the checkbox next to "show advanced options" you then have two advanced options to choose from:
 * 3) If you choose "yes" from the drop-down menu next to "skip the zoom-out when this scene loads" then the transition will be the same as the basic transition except the zoom-out to 100% zoom will be skipped : when the scene is recalled, the molecule will rotate to the new scene's orientation and zoom simultaneously.
 * 4) If instead you choose "yes" from the drop-down menu next to "skip the transition between scenes when this scene loads" then the new scene will just immediately load, without any transition from the previous scene.

Option 1 is the standard. Option 2.1 is helpful when the view is not changing much and you don't want the scene to zoom out completely when transitioning between scenes. Option 1 is helpful when zooming out completely is necessary to give the user proper spatial comprehension when transitioning between two scenes. Option 2.2 is helpful when you really need to have no transition at all (although it should be rarely used except for extreme cases where you really need no transition).

Manipulating Jmol with your mouse

 * Rotate: left click
 * Zoom: scroll button or left click + shift
 * Drag: right click + ctrl
 * Measure distance: dbl click on 1st atom, dbl click on 2nd atom
 * Measure angle: dbl click on 1st atom, click on 2nd atom, dbl click on 3rd atom
 * ''Measure dihedral angle:' dbl click on 1st atom, click on 2nd and 3rd atoms, dbl click on 4th atom

Using Jmol's Command Language
Jmol has an extensive and powerful command language. Users interested in learning the command language can use it within the Scene Authoring Tools. You can enter commands in the bottom portion of the Console. Once you get a scene that you like, save it in the normal way. It doesn't matter how a scene is obtained in Jmol -- it is saved as a state script which reflects the state of Jmol regardless of the path used to arrive at that state.
 * Edit the page, and Show the Molecular Scene Authoring Tools.
 * Click on the Jmol frank within the Jmol applet (lower right from the molecule).
 * In Jmol's Main Menu, click on Console.

The Undo button below Jmol in the Scene Authoring Tools is very useful when you want to undo a command entered via Jmol's Console.

It is also possible to import scenes from other Jmol websites, using a state script. See, for example, Help:Copying FirstGlance Scenes into Proteopedia. Or you might develop a scene in the Jmol Application (as distinct from the Applet) and then transfer the state script.